Skip to main content

World Functions

To manage worlds, use the functions exported by the World adapter.

Importing the adapter​

To use the functions of the World adapter, import it as shown:
import { worldAdapter } from 'epicenter-libs';

The worldAdapter namespace exports functions that make calls to the World API.

learn more

For descriptions of the objects used by the World adapter functions, read World entities.

Worlds​

Create a world​

To create a world , use the create() function. You have the options of specifying a group and/or an episode.

The name of the new world must be unique within the world's scope. You don't have to provide a name. If the name is omitted, Epicenter generates one using a world name generator. There are two types of world name generators:

  • Sequential (default): Generates names of format "World###", where ### is a numeral starting with 001.
  • Color + animal: Randomly combines a color and an animal.

You can specify the type of world name generator you want to use in the worldNameGenerator parameter.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The create() function:

  • Constructs a POST request to the endpoint /world/{groupName} or /world/{groupName}/{episodeName} if an episode name is provided.
  • Sends optional parameters as the request body to configure the world.
  • Returns the created world object.
Function signature
export async function create(  
    optionals: {  
        name?: string,
        displayName?: string,
        groupName?: string,
        episodeName?: string,
        worldNameGenerator?: { objectType: keyof typeof WORLD_NAME_GENERATOR },
        allowChannel?: boolean,
    } & RoutingOptions = {}  
): Promise<World>

Parameters​

warning

A world's name and displayName cannot be an empty string and cannot contain any of these characters:

`$%^*={}[]|;\"<>?\r\n
  • optionals (Type: { name?: string, displayName?: string, groupName?: string, episodeName?: string, worldNameGenerator?: { objectType: keyof typeof WORLD_NAME_GENERATOR }, allowChannel?: boolean } & RoutingOptions = {}):
    • name (string): (Optional) A name for the world. Must be unique within the world's scope.
    • displayName (string): (Optional) An informative display name for the world. Doe not need to be unique.
    • groupName (string): (Optional) The name of the group where the world is created. If not provided, defaults to the groupName stored in the session.
    • episodeName (string): (Optional) The name of the episode in which the world is created.
    • worldNameGenerator ({ objectType: keyof typeof WORLD_NAME_GENERATOR }): (Optional) Specifies the method for generating the world name. A WORLD_NAME_GENERATOR enum value.
    • allowChannel (boolean): (Optional) If true, send out push notifications for this world. Applicable to projects with phylogeny >= SILENT.
    • RoutingOptions: Additional routing options. Pass network call option overrides here.

Return value​

A promise that resolves to the created World object.

Usage example​

import { worldAdapter } from 'epicenter-libs';  

worldAdapter.create({  
    name: 'newWorld',
    displayName: 'Whole new world',
    groupName: 'myGroup',
    episodeName: 'Episode1',
    worldNameGenerator: { objectType: 'colorAnimal' },
    allowChannel: true
});

Retrieve a world​

To retrieve a world associated with a group or episode, use the get() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The get() function:

  • Constructs a GET request to the endpoint /world/{groupName}/{episodeName}.
  • If mine is set to true, only worlds owned by the current user are returned.
  • Defaults to the user's session group if groupName is not provided.
  • Returns the retrieved world object.
Function signature
export async function get(
    optionals: {  
        groupName?: string,
        episodeName?: string,
        mine?: boolean,
    } & RoutingOptions = {}
): Promise<World>

Parameters​

  • optionals (Type: { groupName?: string, episodeName?: string, mine?: boolean } & RoutingOptions = {}):
    • groupName (string): The name of the group. If not provided, defaults to the groupName stored in the session.
    • episodeName (string): The episode name for worlds scoped to an episode.
    • mine (boolean): If true, get only the worlds the requesting user is in (based on session token). Default is false.
    • RoutingOptions: Additional routing options. Pass network call option overrides here.

Return value​

A promise that resolves to a World object.

Usage example​

import { worldAdapter } from 'epicenter-libs';

// Retrieve the world for the groupName stored in the session
worldAdapter.get();

// Retrieve the world for a specific group and episode
worldAdapter.get({ groupName: 'group_1', episodeName: 'episode_1' });

// Retrieve only worlds the current user is in
worldAdapter.get({ mine: true });

List worlds for the current user​

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The getSessionWorlds() function:

  • Constructs a GET request to the endpoint /world/assignment.
  • Retrieves the world associated with the current session.
  • Returns a World object.
Function signature
export async function getSessionWorlds(
    optionals: RoutingOptions = {}
): Promise<World>

Parameters​

Return value​

A promise that resolves to a World object.

Usage example​

import { worldAdapter } from 'epicenter-libs';  

worldAdapter.getSessionWorlds()
    .then(world => console.log(world));

Update a world​

To update an existing world, use the update() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The update() function:

  • Constructs a PATCH request to the endpoint /world/{worldKey}.
  • Sends the updated world properties as the request body.
  • Returns the updated world object.
Function signature
export async function update(  
    worldKey: string,
    update: {
        displayName?: string,
        runKey?: string,
        allowChannel?: boolean
    },
    optionals: RoutingOptions = {}
): Promise<World>

Parameters​

warning

A world's displayName cannot contain any of these characters:

`$%^*={}[]|;\"<>?\r\n
  • worldKey (string): The key identifying the world.
  • update (Type: { displayName?: string, runKey?: string, allowChannel?: boolean }): The world's attributes you are updating.
    • displayName (string): The new display name for the world. Does not need to be unique.
    • runKey (string): The new model run key to associate the world with.
    • allowChannel (boolean): If true, send out push notifications for this world. Applicable to projects with phylogeny >= SILENT.
  • optionals (Type: RoutingOptions = {}): Additional routing options.

Return value​

A promise that resolves to an updated World object.

Usage example​

import { worldAdapter } from 'epicenter-libs';  

worldAdapter.update('0000017a445032dc38cb2cecd5fc56706934',
                    { runKey: '0000018d61f1217b22ce0ae605ff00649d6i', displayName: 'World A1' });

Assign a run to a world​

To assign an existing run to a world, call the assignRun() function.

tip

Use this function when you need to assign the world to a different run.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The assignRun() function:

  • Constructs a PATCH request to the endpoint /world/run/{worldKey}.
  • Assigns a specific run to a given world.
  • Returns the updated World object.
Function signature
export async function assignRun(
    worldKey: string,
    runKey: string,
    optionals: RoutingOptions = {}
): Promise<World>

Parameters​

  • worldKey (string): The unique key identifying the world.
  • runKey (string): The key of the run to be assigned to the world.
  • optionals (Type: RoutingOptions = {}): Additional routing options. Pass network call options overrides here.

Return value​

A promise that resolves to an updated World object.

Usage example​

import { worldAdapter } from 'epicenter-libs';  

await worldAdapter.assignRun('0000017a445032dc38cb2cecd5fc56679324',
                        '0000018d61f1217b22ce0ae605ff00669d8o');

Delete a world​

To delete a world, use the destroy() function.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The destroy() function:

  • Constructs a DELETE request to the endpoint /world/{worldKey}.
  • Sends the worldKey as part of the request URL.
  • Executes the request and returns a void promise upon success.
Function signature
export async function destroy(
    worldKey: string,
    optionals: RoutingOptions = {}
): Promise<void>

Parameters​

  • worldKey (string): The unique key identifying the world to be deleted.
  • optionals (Type: RoutingOptions = {}): Additional routing options.

Return value​

A promise that resolves to void when the world is successfully deleted.

Usage example​

import { worldAdapter } from 'epicenter-libs';  

worldAdapter.destroy('0000017a445032dc38cb2cecd5fc13563218');

User assignments​

List assignments​

Retrieves a list of user assignments with some information on the world included for a group or episode (if specified).

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The getAssignments() function:

  • Constructs a GET request to the endpoint /world/assignment/for/{groupName}/{episodeName}.
  • Retrieves a list of user assignments based on optional filters.
  • Returns an array of World objects.
Function signature
export async function getAssignments(
    optionals: {
        groupName?: string,
        episodeName?: string,
        mine?: boolean,
    } & RoutingOptions = {}
): Promise<World[]>

Parameters​

  • optionals (Type: { groupName?: string, episodeName?: string, mine?: boolean } & RoutingOptions = {}): Filters and additional routing options.
    • groupName (string): The name of the group for which assignments should be retrieved. Defaults to the session's group name.
    • episodeName (string): The episode name for worlds scoped to an episode.
    • mine (boolean): If true, retrieves only the worlds the current user is assigned to.

Return value​

A promise that resolves to an array of World objects.

Usage example​

import { worldAdapter } from 'epicenter-libs';  

worldAdapter.getAssignments({ mine: true }); // Get only the worlds the current user is assigned to.

Assign the current user​

Automatically assigns the current session's user to a world.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The selfAssign() function:

  • Constructs a POST request to the endpoint /world/selfassign/{groupName}/{episodeName}.
  • Assigns the current user to a world with specified parameters.
  • Returns the assigned World object.
Function signature
export async function selfAssign(
    optionals: {
        role?: string,
        groupName?: string,
        episodeName?: string,
        objective?: keyof typeof OBJECTIVE,
        worldNameGenerator?: { objectType: keyof typeof WORLD_NAME_GENERATOR },
        populace?: Persona[],
        allowChannel?: boolean,
    } & RoutingOptions = {}
): Promise<World>

Parameters​

  • optionals (Type: { role?: string, groupName?: string, episodeName?: string, objective?: keyof typeof OBJECTIVE, worldNameGenerator?: { objectType: keyof typeof WORLD_NAME_GENERATOR }, populace?: Persona[], allowChannel?: boolean } & RoutingOptions = {}): Optional arguments. Pass network call options overrides here.
    • role (string): The world role to be assigned to the user.
    • groupName (string): The name of the group. Defaults to the session's group name.
    • episodeName (string): The episode name for worlds scoped to an episode.
    • objective (keyof typeof OBJECTIVE): The assignment objective type. Defaults to OBJECTIVE.MINIMUM.
    • worldNameGenerator ({ objectType: keyof typeof WORLD_NAME_GENERATOR }): Defines the naming convention for the world.
    • populace (Persona[]): List of personas to dictate the self assignment.
    • allowChannel (boolean): If true, enables push notifications for the world. Applicable to projects with phylogeny >= SILENT.

Return value​

A promise that resolves to an assigned World object.

Usage example​

import { worldAdapter } from 'epicenter-libs';
// Assigns user to a group-scoped world
epicenter.worldAdapter.selfAssign();
// Assigns user to a group-scoped world with role "cartographer"
epicenter.worldAdapter.selfAssign({ role: 'cartographer' });
// Assigns user to an episode-scoped world with role "cartographer"
epicenter.worldAdapter.selfAssign({ role: 'cartographer', episodeName: 'my-episode-name' });

Auto-assign users to worlds​

To assign a list of users to world personas, call the autoAssignUsers() function.

This function completes the persona assignments for all existing worlds and creates new worlds for remaining unassigned users. The assignment is done according to the specified assignment objective.

tip

You can make this an all-or-nothing operation by setting the requireAllAssignments to true. In this case all the users in the list must be assigned or none.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The autoAssignUsers() function:

  • Constructs a POST request to the endpoint /world/assignment/{groupName}/{episodeName}.
  • Automatically assigns users to worlds based on specified parameters.
  • Returns an array of assigned World objects.
Function signature
export async function autoAssignUsers(
    assignments: UserAssignment[],
    optionals: {
        groupName?: string,
        episodeName?: string,
        objective?: keyof typeof OBJECTIVE,
        worldNameGenerator?: { objectType: keyof typeof WORLD_NAME_GENERATOR },
        requireAllAssignments?: boolean,
        keepEmptyWorlds?: boolean,
        populace?: Persona[],
        allowChannel?: boolean,
    } & RoutingOptions = {}
): Promise<World[]>

Parameters​

  • assignments (Type: UserAssignment[]): An array of user assignment objects.
  • optionals (Type: { groupName?: string, episodeName?: string, objective?: keyof typeof OBJECTIVE, worldNameGenerator?: { objectType: keyof typeof WORLD_NAME_GENERATOR }, requireAllAssignments?: boolean, keepEmptyWorlds?: boolean, populace?: Persona[], allowChannel?: boolean } & RoutingOptions = {}): Configuration for auto-assigning users.
    • groupName (string): The name of the group. Defaults to the session's group name.
    • episodeName (string): The episode name for episode scoped worlds.
    • objective (keyof typeof OBJECTIVE): The assignment objective type. Defaults to OBJECTIVE.MINIMUM.
    • worldNameGenerator ({ objectType: keyof typeof WORLD_NAME_GENERATOR }): Defines the naming convention for the world.
    • requireAllAssignments (boolean): If true, return an error when an assignment was not made (instead of silently leaving the user as unassigned).
    • keepEmptyWorlds (boolean): If false, worlds that are now empty should be deleted.
    • populace (Persona[]): List of persona objects to assign to worlds.
    • allowChannel (boolean): If true, enables push notifications for the world. Applicable to projects with phylogeny >= SILENT.

Return value​

A promise that resolves to an array of assigned World objects.

Usage example​

import { worldAdapter } from 'epicenter-libs';
    const worlds = await worldAdapter.assignUsers([
                        { userKey: '000001796733eef0842f4d6d960997035d69', role: 'locksmith' },
                        { userKey: '000001796733eef0842f4d6d960997069s5w' },
    ]);

Edit assignments​

Manually assign users to a world. You have the option of specifying a persona for each user.

tip

You can make this an all-or-nothing operation by setting the requireAllAssignments to true. In this case all the users in the list must be assigned or none.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The editAssignments() function:

  • Constructs a PUT request to the endpoint /world/assignment/{groupName}/{episodeName}.
  • Updates user assignments for multiple worlds.
  • Returns an array of updated World objects.
Function signature
export async function editAssignments(
    assignments: Record<WorldKey, UserAssignment[]>,
    optionals: {
        groupName?: string,
        episodeName?: string,
        objective?: keyof typeof OBJECTIVE,
        keepEmptyWorlds?: boolean,
        requireAllAssignments?: boolean,
    } & RoutingOptions = {}
): Promise<World[]>

Parameters​

  • assignments (Type: Record<WorldKey, UserAssignment[]>): A mapping of world keys to user assignments.
  • optionals (Type: { groupName?: string, episodeName?: string, objective?: keyof typeof OBJECTIVE, keepEmptyWorlds?: boolean, requireAllAssignments?: boolean } & RoutingOptions = {}): Configuration for editing assignments.
    • groupName (string): The name of the group for which assignments are updated. Defaults to the session's group name.
    • episodeName (string): The episode name for worlds scoped to an episode.
    • objective (keyof typeof OBJECTIVE): The assignment objective type. Defaults to OBJECTIVE.MINIMUM.
    • keepEmptyWorlds (boolean): If true, worlds with no assigned users are still maintained.
    • requireAllAssignments (boolean): If true, return an error when an assignment was not made (instead of silently leaving the user as unassigned).

Return value​

A promise that resolves to an array of updated World objects.

Usage example​

import { worldAdapter } from 'epicenter-libs';  

const assignments: Record<WorldKey, UserAssignment[]> = {
    'world123': [{ userId: 'user123', role: 'leader' }],
    'world456': [{ userId: 'user456', role: 'member' }]
};

worldAdapter.editAssignments(assignments, { groupName: 'Team Alpha', episodeName: 'Episode 1' })
    .then(updatedWorlds => console.log(updatedWorlds));

Get assignments for a world​

To retrieve the current assignments for a world, call the getAssignmentsByKey() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The getAssignmentsByKey() function:

  • Constructs a GET request to the endpoint /world/assignment/{worldKey}.
  • Retrieves the assignment details for a specific world.
  • Returns the corresponding World object.
Function signature
export async function getAssignmentsByKey(
    worldKey: string,
    optionals: RoutingOptions = {}
): Promise<World>

Parameters​

  • worldKey (string): The unique key identifying the world.
  • optionals (Type: RoutingOptions = {}): Additional routing options. Pass network call options overrides here.

Return value​

A promise that resolves to a World object.

Usage example​

import { worldAdapter } from 'epicenter-libs';  
const assignments = await worldAdapter.getAssignmentsByKey(world.worldKey);

Remove users​

To remove a user of a set of users from assignments, call removeUsers() function.

warning

Any worlds that do not contain users within them will be automatically deleted in the process unless you unless you set the keepEmptyWorlds parameter to true.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The removeUsers() function:

  • Constructs a DELETE request to the endpoint /world/assignment/{groupName}/{episodeName}.
  • Removes users from world assignments based on specified parameters.
  • Returns a void promise upon success.
Function signature
export async function removeUsers(
    userKeys: string[],
    optionals: {
        groupName?: string,
        episodeName?: string,
        keepEmptyWorlds?: boolean,
    } & RoutingOptions = {}
): Promise<void>

Parameters​

  • userKeys (Type: string[]): An array of user keys to be removed from their world persona assignments.
  • optionals (Type: { groupName?: string, episodeName?: string, keepEmptyWorlds?: boolean } & RoutingOptions = {}): Optional arguments. Pass network call options overrides here.
    • groupName (string): The name of the group. Defaults to the session's group name.
    • episodeName (string): The episode name for worlds scoped to an episode.
    • keepEmptyWorlds (boolean): If false, worlds that have no assigned users as a result of the function call are deleted.

Return value​

A promise that resolves to void when the users are successfully removed.

Usage example​

import { worldAdapter } from 'epicenter-libs';
const usersToRemove = ['000001796733eef0842f4d6d960997639ww5r'];
await worldAdapter.removeUsers(usersToRemove);

Personas​

List personas​

To get a list of the personas for a given scope (project, group, episode, or world), call the getPersonas() function.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The getPersonas() function:

  • Retrieves personas associated with a specific scope.
  • Returns a void promise upon success.
Function signature
export async function getPersonas(
    scope: GenericScope,
    optionals: RoutingOptions = {}
): Promise<void>

Parameters​

  • scope (Type: GenericScope): The scope defining the level at which personas are retrieved.
    • scopeBoundary (string): The boundary level for the scope. Defaults to PROJECT.
    • scopeKey (string): The specific key within the scope.
  • optionals (Type: RoutingOptions = {}): Additional routing options.

Return value​

A promise that resolves to void when the personas are successfully retrieved.

Usage example​

import { worldAdapter } from 'epicenter-libs';  
await worldAdapter.getPersonas({ scopeBoundary: SCOPE_BOUNDARY.GROUP, scopeKey: GROUP_KEY });

Set personas​

To set the personas of a given entity (project, group, episode, or world), call the setPersonas() function.

Note

The setPersonas() function performs an overwrite of the set of personas for an entity. You must always pass the entire array.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

The setPersonas() function:

  • Sets personas with specific roles and constraints within a given scope.
  • Returns a void promise upon success.
Function signature
export async function setPersonas(
    personas: { role: string, minimum?: number, maximum?: number, marginal?: number }[],
    scope: GenericScope,
    optionals: RoutingOptions = {}
): Promise<void>

Parameters​

Return value​

A promise that resolves to void when the personas are successfully set.

Usage example​

import { worldAdapter } from 'epicenter-libs';  

const personas = [
    { role: 'Leader', minimum: 1, maximum: 1 },
    { role: 'Member', minimum: 2, maximum: 10 }
];

const scope = { scopeBoundary: SCOPE_BOUNDARY.GROUP, scopeKey: GROUP_KEY };

await worldAdapter.setPersonas(personas, scope);